﻿@page "/docs/extensions/markdown"

<Seo Canonical="/docs/extensions/markdown" Title="Blazorise Markdown component" Description="Learn to use and work with the Blazorise Markdown component, which allows you to edit markdown based strings." />

<DocsPageTitle Path="Extensions/Markdown">
    Blazorise Markdown component
</DocsPageTitle>

<DocsPageLead>
    The <Code>Markdown</Code> component allows you to edit markdown strings.
</DocsPageLead>

<DocsPageParagraph>
    The Blazorise <Code>Markdown</Code> is based on the <Blazorise.Link To="https://github.com/Ionaru/easy-markdown-editor" Target="Target.Blank">Easy MarkDown Editor</Blazorise.Link> JavaScript library.
</DocsPageParagraph>

<DocsPageSubtitle>
    Installation
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="NuGet">
        Install extension from NuGet.
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="MarkdownNugetInstallExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Imports">
        In your main <Badge Color="Color.Light">_Imports.razor</Badge> add:
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="ImportMarkdownExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Example" />
    <DocsPageSectionContent Outlined FullWidth>
        <MarkdownExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="MarkdownExample" />
</DocsPageSection>

<Alert Color="Color.Info" Visible>
    <AlertDescription>
        For transforming markdown value into HTML we used an excellent <Blazorise.Link To="https://github.com/xoofx/markdig" Target="Target.Blank">Markdig</Blazorise.Link> library.
    </AlertDescription>
</Alert>

<DocsPageSection>
    <DocsPageSectionHeader Title="Toolbar customization">
        The editor's toolbar can be edited to show more icons and even add custom icons!
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <MarkdownCustomButtonsExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="MarkdownCustomButtonsExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Upload image">
        Uploading image has a similar API to our FileEdit component and it is fairly simple to do.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <MarkdownUploadImageExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="MarkdownUploadImageExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Change Shortcuts">
        EasyMDE comes with an array of predefined keyboard shortcuts, but they can be altered with a configuration option.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <MarkdownShortcutsExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="MarkdownShortcutsExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Custom Preview Render">
        Sometimes you don't want to render preview with the built-in parser. In those situations you can make use of <Code>PreviewRender</Code> callback to override the preview HTML.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <MarkdownPreviewRenderExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="MarkdownPreviewRenderExample" />
</DocsPageSection>

<DocsPageSubtitle>
    API
</DocsPageSubtitle>

<Heading Size="HeadingSize.Is3">
    Attributes
</Heading>

<DocsAttributes>
    <DocsAttributesItem Name="Value" Type="string" Default="null">
        Gets or sets the markdown value.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ValueChanged" Type="EventCallback<string>" Default="Solid">
        An event that occurs after the markdown value has changed.
    </DocsAttributesItem>
    <DocsAttributesItem Name="AutoDownloadFontAwesome" Type="bool?" Default="null">
        If set to true, force downloads Font Awesome (used for icons). If set to false, prevents downloading.
    </DocsAttributesItem>
    <DocsAttributesItem Name="LineNumbers" Type="bool" Default="false">
        If set to true, enables line numbers in the editor.
    </DocsAttributesItem>
    <DocsAttributesItem Name="LineWrapping" Type="bool" Default="false">
        If set to false, disable line wrapping. Defaults to true.
    </DocsAttributesItem>
    <DocsAttributesItem Name="MinHeight" Type="string" Default="300px">
        Sets the minimum height for the composition area, before it starts auto-growing.
        Should be a string containing a valid CSS value like "500px". Defaults to "300px".
    </DocsAttributesItem>
    <DocsAttributesItem Name="MaxHeight" Type="string" Default="">
        Sets fixed height for the composition area. minHeight option will be ignored.
        Should be a string containing a valid CSS value like "500px". Defaults to undefined.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Placeholder" Type="string" Default="null">
        If set, displays a custom placeholder message.
    </DocsAttributesItem>
    <DocsAttributesItem Name="TabSize" Type="int" Default="2">
        If set, customize the tab size. Defaults to 2.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Theme" Type="string" Default="easymde">
        Override the theme. Defaults to easymde.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Direction" Type="string" Default="ltr">
        rtl or ltr. Changes text direction to support right-to-left languages. Defaults to ltr.
    </DocsAttributesItem>
    <DocsAttributesItem Name="HideIcons" Type="string[]" Default="'side-by-side', 'fullscreen'">
        An array of icon names to hide. Can be used to hide specific icons shown by default without
        completely customizing the toolbar.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ShowIcons" Type="string[]" Default="'code', 'table'">
        An array of icon names to show. Can be used to show specific icons hidden by default without
        completely customizing the toolbar.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Toolbar" Type="RenderFragment" Default="">
        [Optional] Gets or sets the content of the toolbar.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ToolbarTips" Type="bool" Default="true">
        If set to false, disable toolbar button tips. Defaults to true.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ToolbarButtonClassPrefix" Type="string" Default="mde">
        Adds a prefix to the toolbar button classes when set. For example, a value of <Code>"mde"</Code> results in <Code>"mde-bold"</Code> for the Bold button.
    </DocsAttributesItem>
    <DocsAttributesItem Name="CustomButtonClicked" Type="EventCallback<MarkdownButtonEventArgs>" Default="">
        Occurs after the custom toolbar button is clicked.
    </DocsAttributesItem>
    <DocsAttributesItem Name="UploadImage" Type="bool" Default="true">
        If set to true, enables the image upload functionality, which can be triggered by drag-drop,
        copy-paste and through the browse-file window (opened when the user click on the upload-image icon).
        Defaults to true.
    </DocsAttributesItem>
    <DocsAttributesItem Name="MaxUploadImageChunkSize" Type="long" Default="20 * 1024">
        Gets or sets the max chunk size when uploading the file.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SegmentFetchTimeout" Type="TimeSpan" Default="1 min">
        Gets or sets the Segment Fetch Timeout when uploading the file.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageMaxSize" Type="long" Default="1024*1024*2 (2Mb)">
        Maximum image size in bytes, checked before upload (note: never trust client, always check image
        size at server-side). Defaults to 1024*1024*2 (2Mb).
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageAccept" Type="string" Default="image/png, image/jpeg">
        A comma-separated list of mime-types used to check image type before upload (note: never trust client, always
        check file types at server-side). Defaults to image/png, image/jpeg.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageUploadEndpoint" Type="string">
        The endpoint where the images data will be sent, via an asynchronous POST request. The server is supposed to
        save this image, and return a json response.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImagePathAbsolute" Type="string">
        If set to true, will treat imageUrl from imageUploadFunction and filePath returned from imageUploadEndpoint as
        an absolute rather than relative path, i.e. not prepend window.location.origin to it.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageCSRFToken" Type="string">
        CSRF token to include with AJAX call to upload image. For instance used with Django backend.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageTexts" Type="MarkdownImageTexts" Default="null">
        Texts displayed to the user (mainly on the status bar) for the import image feature, where
        #image_name#, #image_size# and #image_max_size# will replaced by their respective values, that
        can be used for customization or internationalization.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageUploadChanged" Type="Func<FileChangedEventArgs, Task>">
        Occurs every time the selected image has changed.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageUploadStarted" Type="Func<FileStartedEventArgs, Task>">
        Occurs when an individual image upload has started.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageUploadEnded" Type="Func<FileEndedEventArgs, Task>">
        Occurs when an individual image upload has ended.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageUploadWritten" Type="Func<FileWrittenEventArgs, Task>">
        Occurs every time the part of image has being written to the destination stream.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ImageUploadProgressed" Type="Func<FileProgressedEventArgs, Task>">
        Notifies the progress of image being written to the destination stream.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ErrorMessages" Type="MarkdownErrorMessages">
        Errors displayed to the user, using the errorCallback option, where #image_name#, #image_size#
        and #image_max_size# will replaced by their respective values, that can be used for customization
        or internationalization.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ErrorCallback" Type="Func<string, Task>">
        A callback function used to define how to display an error message. Defaults to (errorMessage) => alert(errorMessage).
    </DocsAttributesItem>
    <DocsAttributesItem Name="Autofocus" Type="bool" Default="false">
        If set to true, focuses the editor automatically. Defaults to false.
    </DocsAttributesItem>
    <DocsAttributesItem Name="AutoRefresh" Type="MarkdownAutoRefresh">
        Useful, when initializing the editor in a hidden DOM node. If set to { delay: 300 },
        it will check every 300 ms if the editor is visible and if positive, call CodeMirror's refresh().
    </DocsAttributesItem>
    <DocsAttributesItem Name="Autosave" Type="MarkdownAutosave">
        Saves the text that's being written and will load it back in the future.
        It will forget the text when the form it's contained in is submitted.
    </DocsAttributesItem>
    <DocsAttributesItem Name="BlockStyles" Type="MarkdownBlockStyles">
        Customize how certain buttons that style blocks of text behave.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ForceSync" Type="bool" Default="false">
        If set to true, force text changes made in EasyMDE to be immediately stored in original text area.
        Defaults to false.
    </DocsAttributesItem>
    <DocsAttributesItem Name="IndentWithTabs" Type="bool" Default="true">
        If set to false, indent using spaces instead of tabs. Defaults to true.
    </DocsAttributesItem>
    <DocsAttributesItem Name="InputStyle" Type="string" Default="null">
        textarea or contenteditable.
        Defaults to textarea for desktop and contenteditable for mobile.
        contenteditable option is necessary to enable nativeSpellcheck.
    </DocsAttributesItem>
    <DocsAttributesItem Name="InsertTexts" Type="MarkdownInsertTexts">
        Customize how certain buttons that insert text behave. Takes an array with two elements.
        The first element will be the text inserted before the cursor or highlight, and the second
        element will be inserted after.
        For example, this is the default link value: ["[", "](http://)"].
    </DocsAttributesItem>
    <DocsAttributesItem Name="NativeSpellcheck" Type="bool" Default="true">
        If set to false, disable native spell checker. Defaults to true.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ParsingConfig" Type="MarkdownParsingConfig">
        Adjust settings for parsing the Markdown during editing (not previewing).
    </DocsAttributesItem>
    <DocsAttributesItem Name="PreviewClass" Type="string" Default="editor-preview">
        A space-separated string that will be applied to the preview screen when activated.
        Defaults to "editor-preview".
    </DocsAttributesItem>
    <DocsAttributesItem Name="PreviewImagesInEditor" Type="bool" Default="false">
        EasyMDE will show preview of images, false by default,
        preview for images will appear only for images on separate lines.
    </DocsAttributesItem>
    <DocsAttributesItem Name="PromptTexts" Type="MarkdownPromptTexts">
        Customize the text used to prompt for URLs.
    </DocsAttributesItem>
    <DocsAttributesItem Name="PromptURLs" Type="bool" Default="false">
        If set to true, a JS alert window appears asking for the link or image URL.
        Defaults to false.
    </DocsAttributesItem>
    <DocsAttributesItem Name="RenderingConfig" Type="MarkdownRenderingConfig">
        Adjust settings for parsing the Markdown during previewing (not editing).
    </DocsAttributesItem>
    <DocsAttributesItem Name="ScrollbarStyle" Type="string" Default="native">
        Chooses a scrollbar implementation.
        The default is "native", showing native scrollbars.

        The core library also provides the "null" style, which completely hides the scrollbars.
        Addons can implement additional scrollbar models.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Shortcuts" Type="MarkdownShortcuts">
        Keyboard shortcuts associated with this instance.
        Defaults to the array of <see href="https://github.com/Ionaru/easy-markdown-editor#keyboard-shortcuts">shortcuts</see>.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SideBySideFullscreen" Type="bool" Default="false">
        If set to false, allows side-by-side editing without going into fullscreen. Defaults to false.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SpellChecker" Type="bool" Default="true">
        If set to false, disable the spell checker. Defaults to true
    </DocsAttributesItem>
    <DocsAttributesItem Name="Status" Type="string[]" Default="null">
        If set to empty array, hide the status bar. Defaults to the array of built-in status bar items.
        Optionally, you can set an array of status bar items to include, and in what order.
    </DocsAttributesItem>
    <DocsAttributesItem Name="StyleSelectedText" Type="bool" Default="true">
        If set to false, remove the CodeMirror-selectedtext class from selected lines. Defaults to true.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SyncSideBySidePreviewScroll" Type="bool" Default="true">
        If set to false, disable syncing scroll in side by side mode. Defaults to true.
    </DocsAttributesItem>
    <DocsAttributesItem Name="UnorderedListStyle" Type="string" Default="*">
        can be *, - or +. Defaults to *.
    </DocsAttributesItem>
    <DocsAttributesItem Name="DisableProgressReport" Type="bool" Default="false">
        Gets or sets whether report progress should be disabled. By enabling this setting, ImageUploadProgressed and ImageUploadWritten callbacks won't be called. Internal file progress won't be tracked.
        This setting can speed up file transfer considerably.
    </DocsAttributesItem>
    <DocsAttributesItem Name="PreviewRender" Type="Func<string, Task<string>>" Default="null">
        Custom function for parsing the plaintext Markdown and returning HTML. Used when user previews.
    </DocsAttributesItem>
</DocsAttributes>